From 5a173df3da13c383179c3c193496b87d8019b061 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 8 Jul 2020 14:42:32 +0100 Subject: [PATCH] Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference. --- docs/reference/gtk/gtk4-docs.xml | 7 ++ docs/reference/gtk/gtk4-sections.txt | 38 ++++++ docs/reference/gtk/gtk4.types.in | 1 + docs/reference/gtk/meson.build | 1 + docs/reference/gtk/section-accessibility.md | 121 ++++++++++++++++++++ 5 files changed, 168 insertions(+) create mode 100644 docs/reference/gtk/section-accessibility.md diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml index 37b22c4d80..f65688b0fd 100644 --- a/docs/reference/gtk/gtk4-docs.xml +++ b/docs/reference/gtk/gtk4-docs.xml @@ -338,6 +338,13 @@ + + Accessibility + + + + + Miscellaneous diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt index 5026765ca3..c0c0f80561 100644 --- a/docs/reference/gtk/gtk4-sections.txt +++ b/docs/reference/gtk/gtk4-sections.txt @@ -7652,3 +7652,41 @@ gtk_selection_filter_model_new_for_type gtk_selection_filter_model_set_model gtk_selection_filter_model_get_model + +
+gtkaccessible +GtkAccessible +GtkAccessibleRole +GtkAccessibleState +GtkAccessibleProperty +gtk_accessible_update_state + +GTK_TYPE_ACCESSIBLE +GTK_TYPE_ACCESSIBLE_PROPERTY +GTK_TYPE_ACCESSIBLE_ROLE +GTK_TYPE_ACCESSIBLE_STATE +GTK_ACCESSIBLE +GTK_ACCESSIBLE_GET_IFACE +GTK_IS_ACCESSIBLE + +gtk_accessible_get_type +
+ +
+gtkatcontext +GtkATContext +gtk_at_context_get_accessible +gtk_at_context_get_accessible_role + +gtk_at_context_create + +GTK_TYPE_AT_CONTEXT +GTK_AT_CONTEXT +GTK_AT_CONTEXT_CLASS +GTK_AT_CONTEXT_GET_CLASS +GTK_IS_AT_CONTEXT +GTK_IS_AT_CONTEXT_CLASS + +GtkATContextClass +gtk_at_context_get_type +
diff --git a/docs/reference/gtk/gtk4.types.in b/docs/reference/gtk/gtk4.types.in index e24296bb44..39c3ab5572 100644 --- a/docs/reference/gtk/gtk4.types.in +++ b/docs/reference/gtk/gtk4.types.in @@ -17,6 +17,7 @@ gtk_application_window_get_type gtk_aspect_frame_get_type gtk_assistant_get_type gtk_assistant_page_get_type +gtk_at_context_get_type gtk_bin_layout_get_type gtk_bitset_get_type gtk_expression_get_type diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build index af14959544..d13686fec7 100644 --- a/docs/reference/gtk/meson.build +++ b/docs/reference/gtk/meson.build @@ -393,6 +393,7 @@ expand_content_md_files = [ 'drawing-model.md', 'css-overview.md', 'css-properties.md', + 'section-accessibility.md', 'section-text-widget.md', 'section-tree-widget.md', 'section-list-widget.md', diff --git a/docs/reference/gtk/section-accessibility.md b/docs/reference/gtk/section-accessibility.md new file mode 100644 index 0000000000..84c361a92f --- /dev/null +++ b/docs/reference/gtk/section-accessibility.md @@ -0,0 +1,121 @@ +# GTK Accessibility {#gtk-accessibility} + +## The standard accessibility interface + +The #GtkAccessible interface provides the accessibility information about +an application's user interface elements. Assistive technology (AT) +applications, like Orca, convey this information to users with disabilities, +or reduced abilities, to help them use the application. + +Standard GTK controls implement the #GtkAccessible interface and are thus +accessible to ATs by default. This means that if you use GTK controls such +as #GtkButton, #GtkEntry, or #GtkListView, you only need to supply +application-specific details when the defaults values are incomplete. You +can do this by setting the appropriate properties in your #GtkBuilder +template and UI definition files, or by setting the properties defined by +the #GtkAccessible interface. + +If you are implementing your own #GtkWidget derived type, you will need to +set the #GtkAccessible properties yourself, and provide an implementation +of the #GtkAccessible virtual functions. + +## Accessible roles and states + +The fundamental concepts of an accessible widget are *roles* and *states*; +each GTK control fills out a role and its functionality is described by a +set of *states*. + +### Roles + +Roles define the taxonomy and semantics of a UI control to any assistive +technology application; for instance, a button will have a role of +%GTK\_ACCESSIBLE\_ROLE\_BUTTON`; an entry will have a role of +%GTK\_ACCESSIBLE\_ROLE\_TEXTBOX`; a toggle button will have a role of +%GTK\_ACCESSIBLE\_ROLE\_CHECKBOX`; etc. + +Each role is part of the widget's instance, and **CANNOT** be changed over +time or as the result of a user action. Roles allows assistive technology +applications to identify a UI control and decide how to present it to a +user; if a part of the application's UI changes role, the control needs to +be removed and replaced with another one with the appropriate role. + +#### List of accessible roles + +Each role name is part of the `GtkAccessibleRole` enumeration. +| Role name | Description | +|-----------|-------------| +| `ALERT` | A message with important information | +| `BUTTON` | A control that performs an action when pressed | +| `CHECKBOX` | A control that has three possible value: `true`, `false`, or `undefined` | +| `COLUMNHEADER` | The header of a column in a list or grid | +| `COMBOBOX` | A control that can be expanded to show a list of possible values to select | +| `...` | … | + +See the [WAI-ARIA](https://www.w3.org/WAI/PF/aria/appendices#quickref) list +of roles for additional information. + +### States + +States, or properties, provide specific information about an accessible UI +control, and describe it for the assistive technology applications. + +Unlike roles, states may change over time, or in response to user action; +for instance, a toggle button will change its %GTK\_ACCESSIBLE\_STATE\_CHECKED +state every time it is toggled, either by the user or programmatically. + +#### List of accessible states + +Each state name is part of the #GtkAccessibleState enumeration. +| State name | Description | +|------------|-------------| +| `...` | … | + +See the [WAI-ARIA](https://www.w3.org/WAI/PF/aria/appendices#quickref) list of states for additional information. + +## Application development rules + +Even if standard UI controls provided by GTK have accessibility information +out of the box, there are some additional properties and considerations for +application developers. For instance, if your application presents the user +with a form to fill out, you should ensure that: + + * the container of the form has a `Gtk.AccessibleRole.FORM` role + * each text entry widget in the form has the `GtkAccessible:labelled-by` + property pointing to the label widget that describes it + +Another example: if you create a tool bar containing buttons with only icons, you should ensure that: + + * the container has a `Gtk.AccessibleRole.TOOLBAR` role + * each button has a `GtkAccessible:label` property set with the user + readable and localised action performed when pressed; for instance "Copy", + "Paste", "Add layer", or "Remove" + +GTK will try to fill in some information by using ancillary UI control +property, for instance the accessible label will be taken from the label or +placeholder text used by the UI control, or from its tooltip, if the +`GtkAccessible:label` or the `GtkAccessible:labelled-by` properties are +unset. Nevertheless, it is good practice and project hygiene to explicitly +specify the accessible properties, just like it's good practice to specify +tooltips and style classes. + +Application developers using GTK **SHOULD** ensure that their UI controls +are accessible as part of the development process. When using `GtkBuilder` +templates and UI definition files, GTK provides a validation tool that +verifies that each UI element has a valid role and properties; this tool can +be used as part of the application's test suite to avoid regressions. + +## Implementations + +Each UI control implements the `GtkAccessible` interface to allow widget and +application developers to specify the roles, state, and relations between UI +controls. This API is purely descriptive. + +Each `GtkAccessible` implementation must provide a `GtkATContext` instance, +which acts as a proxy to the specific platform's accessibility API: + + * AT-SPI on Linux/BSD + * NSAccessibility on macOS + * Active Accessibility on Windows + +Additionally, an ad hoc accessibility backend is available for the GTK +testsuite, to ensure reproducibility of issues in the CI pipeline. -- 2.30.2